Next: Infinite Loops, Up: Debugger [Contents][Index]
The most important time to enter the debugger is when a Lisp error happens. This allows you to investigate the immediate causes of the error.
However, entry to the debugger is not a normal consequence of
an error. Many commands signal Lisp errors when invoked
inappropriately, and during ordinary editing it would be very
inconvenient to enter the debugger each time this happens. So if
you want errors to enter the debugger, set the variable
debug-on-error to non-nil. (The command
toggle-debug-on-error provides an easy way to do
this.)
This variable determines whether the debugger is called
when an error is signaled and not handled. If
debug-on-error is t, all kinds of
errors call the debugger, except those listed in
debug-ignored-errors (see below). If it is
nil, none call the debugger.
The value can also be a list of error conditions (see
Signaling
Errors). Then the debugger is called only for error
conditions in this list (except those also listed in
debug-ignored-errors). For example, if you set
debug-on-error to the list
(void-variable), the debugger is only called for
errors about a variable that has no value.
Note that eval-expression-debug-on-error
overrides this variable in some cases; see below.
When this variable is non-nil, Emacs does not
create an error handler around process filter functions and
sentinels. Therefore, errors in these functions also invoke
the debugger. See Processes.
This variable specifies errors which should not enter the
debugger, regardless of the value of
debug-on-error. Its value is a list of error
condition symbols and/or regular expressions. If the error
has any of those condition symbols, or if the error message
matches any of the regular expressions, then that error does
not enter the debugger.
The normal value of this variable includes
user-error, as well as several errors that
happen often during editing but rarely result from bugs in
Lisp programs. However, “rarely” is not
“never”; if your program fails with an error that
matches this list, you may try changing this list to debug
the error. The easiest way is usually to set
debug-ignored-errors to nil.
If this variable has a non-nil value (the
default), running the command eval-expression
causes debug-on-error to be temporarily bound to
to t. See
Evaluating Emacs-Lisp Expressions in The GNU Emacs
Manual.
If eval-expression-debug-on-error is
nil, then the value of
debug-on-error is not changed during
eval-expression.
Normally, errors caught by condition-case
never invoke the debugger. The condition-case
gets a chance to handle the error before the debugger gets a
chance.
If you change debug-on-signal to a
non-nil value, the debugger gets the first
chance at every error, regardless of the presence of
condition-case. (To invoke the debugger, the
error must still fulfill the criteria specified by
debug-on-error and
debug-ignored-errors.)
Warning: Setting this variable to
non-nil may have annoying effects. Various parts
of Emacs catch errors in the normal course of affairs, and
you may not even realize that errors happen there. If you
need to debug code wrapped in condition-case,
consider using condition-case-unless-debug (see
Handling
Errors).
If you set debug-on-event to a special event
(see Special
Events), Emacs will try to enter the debugger as soon as
it receives this event, bypassing
special-event-map. At present, the only
supported values correspond to the signals
SIGUSR1 and SIGUSR2 (this is the
default). This can be helpful when inhibit-quit
is set and Emacs is not otherwise responding.
If you set debug-on-message to a regular
expression, Emacs will enter the debugger if it displays a
matching message in the echo area. For example, this can be
useful when trying to find the cause of a particular
message.
To debug an error that happens during loading of the init
file, use the option ‘--debug-init’.
This binds debug-on-error to t while
loading the init file, and bypasses the
condition-case which normally catches errors in the
init file.
Next: Infinite Loops, Up: Debugger [Contents][Index]